14.8.2.4 :dir and remote execution

While the :file header argument can be used to specify the path to the output file, :dir specifies the default directory during code block execution. If it is absent, then the directory associated with the current buffer is used. In other words, supplying :dir path temporarily has the same effect as changing the current directory with M-x cd path, and then not supplying :dir. Under the surface, :dir simply sets the value of the Emacs variable default-directory.

When using :dir, you should supply a relative path for file output (e.g. :file myfile.jpg or :file results/myfile.jpg) in which case that path will be interpreted relative to the default directory.

In other words, if you want your plot to go into a folder called Work in your home directory, you could use

     #+begin_src R :file myplot.png :dir ~/Work
     matplot(matrix(rnorm(100), 10), type="l")
     #+end_src

Remote execution

A directory on a remote machine can be specified using tramp file syntax, in which case the code will be evaluated on the remote machine. An example is

     #+begin_src R :file plot.png :dir /dand@yakuba.princeton.edu:
     plot(1:10, main=system("hostname", intern=TRUE))
     #+end_src

Text results will be returned to the local Org-mode buffer as usual, and file output will be created on the remote machine with relative paths interpreted relative to the remote directory. An Org-mode link to the remote file will be created.

So, in the above example a plot will be created on the remote machine, and a link of the following form will be inserted in the org buffer:

     [[file:/scp:dand@yakuba.princeton.edu:/home/dand/plot.png][plot.png]]

Most of this functionality follows immediately from the fact that :dir sets the value of the Emacs variable default-directory, thanks to tramp. Those using XEmacs, or GNU Emacs prior to version 23 may need to install tramp separately in order for these features to work correctly.

Further points

• If :dir is used in conjunction with :session, although it will determine the starting directory for a new session as expected, no attempt is currently made to alter the directory associated with an existing session.
• :dir should typically not be used to create files during export with :exports results or :exports both. The reason is that, in order to retain portability of exported material between machines, during export links inserted into the buffer will *not* be expanded against default directory. Therefore, if default-directory is altered using :dir, it is probable that the file will be created in a location to which the link does not point.